Software Vault: The Gold Collection

home *** CD-ROM | disk | FTP | other *** search

/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr35 / vbbs61a2.zip / VSCRIPT.DOC < prev next >

Wrap

Text File | 1993-05-30 | 113KB | 2,698 lines

██┐ ██┐ ████████┐ ████████┐ ███████┐ ██│ ██│ └██┌──██│ └██┌──██│ ██┌────┘ ██┐ ██┌┘ ███████│ ███████│ ███████┐ ██┐██┌┘ ██┌──██│ ██┌──██│ └────██│ ███┌┘ ████████│ ████████│ ███████│ └──┘ └───────┘ └───────┘ └──────┘ * The Virtual BBS/NET Version 6.10 (C) Roland De Graaf 1990, 1991, 1992, 1993 4246 Elisabeth Ave. Holland, MI 49424 * ═════════════════════════════════════════════════════════════════ VBBS VSCRIPT Documentation ═════════════════════════════════════════════════════════════════ Written By: Tom Hightower, aka "Baloo" 1@1806000 VirtualNET Kevin Klunk, aka "Lord Doomslayer" 2@1508000 VirtualNET Format By: Sam Fleming, aka "O. F." 1@1205500 VirtualNET ═════════════════════════════════════════════════════════════════ TABLE OF CONTENTS (1) General VSCRIPT Information 1.1 - Script Language Introduction 1.2 - General Restrictions 1.3 - Script Compiler (VCOM.EXE) 1.4 - Command Format 1.5 - Special Variables/Constants 1.6 - Interfacing with VBBS 1.7 - Prepackaged Scripts (2) Number and String Handling 2.1 - Numeric Operators 2.2 - Numeric Functions 2.3 - String Operators 2.4 - String Functions 2.5 - String Alterations (3) Display and I/O Commands 3.1 - Reading Input 3.2 - Showing Line Output 3.3 - Colorization 3.4 - Other Display Commands (4) Database & Message Commands 4.1 - Database Selection 4.2 - LOAD Related Commands 4.3 - Editing Commands 4.4 - Viewing & Writing 4.5 - E-mail Functions (5) Buffer Operation & Use (6) File Commands 6.1 - Information Commands 6.2 - Transfer Commands 6.3 - File Editing (7) Control Commands 7.1 - General Redirection 7.2 - Loops & Comparisons 7.21 - DO Loops 7.22 - IF/IFVAL Structures 7.23 - TEST/TESTVAL Commands 7.3 - Passing Control (8) Miscellaneous Commands 8.1 - Visual/Interactive 8.2 - User Modifiers 8.3 - Real Miscellany APPENDIX A - VGIX Commands APPENDIX B - Programmer's Reference Guide APPENDIX C - Script/Function Block Commands APPENDIX D - Common Script Examples VSCRIPT Documentation -- 1 ╔════════════════════════════════════════════════════════════════╗ ║ (1) GENERAL VSCRIPT INFORMATION ║ ╚════════════════════════════════════════════════════════════════╝ 1.1 - Script Language Introduction ══════════════════════════════════ One of the features that makes VBBS unique is its script language compiler - VCOM.EXE. Along with the built-in command interpreter in VBBS, it allows you to make changes to your BBS quickly and easily. The scripts are nothing more than a series of commands listed in a plain ASCII text file, and you don't even need to be a programmer to write one. All you need to cre- ate scripts are a text editor or word processor that allows you to save in ASCII format (see your word processor documentation for more info) and a little patience. In no time, you will be writing up scripts and swapping them with other VBBS sysops like a pro. 1.2 - General Restrictions ══════════════════════════ The VBBS script language has only one major restriction: there can only be a total of 7 'tokens' on a line. A token is defined as either a single unspaced series of characters (for example, a command or a number) or any group of characters and spaces surrounded by single or double quotes (also called a "string".) The script language is NOT case-sensitive; any capitalization used in this text is not required and is done only for clarity. All the scripts that you create should be placed into your scripts directory as defined in VCONFIG - PATHS Configuration; see VBBS.DOC for more information on setting your paths. The only other restrictions pertain to names. All of your script files MUST have the extension .V and all of your names for variables must begin with a '$', e.g., $variable. 1.3 - Script Compiler (VCOM.EXE) ════════════════════════════════ The program VCOM.EXE is the compiler that prepares your script file for use by VBBS's interpreter. It takes the script file that you have created and builds the two files that VBBS actually uses from it. These two files have the same name as the script file but have .LIT and .COD as their extensions. Compilation of a script is accomplished by changing to your scripts directory and executing the command line: VCOM <script name> VSCRIPT Documentation -- 2 You do not need to use the extension to compile the script. The compiler can detect some errors in the script file during the compilation. These errors are predominantly related to the commands that 'jump' around within a script. These commands are GO, TEST, TESTVAL, CALL, and BREAK. If an error is found the compiler will abort and you will need to go into your script to correct the error. 1.4 - Command Format ════════════════════ All commands will be listed in the form: Command Name -> Command Syntax. <description of command here> The following conventions will be used in all command syntax in this document: COMMAND - All commands will be in capitals and must be typed in the format shown (see the note below.) <label> - A single word, no quotes or spaces. <variable#> - Any variable name (only). <number#> - Any numeric value (only). <string#> - A string value ("aBc 123") or any variable name. <value#> - A numeric value or any variable name that is used to store numeric values. <pathfile#> - A legal DOS filename including path information. If the path is excluded it will default to the BBS' main directory. A variable that stores the correct path/filename info may also be used. <filename#> - A legal DOS filename excluding path information. Commands that use this have the path info set automatically. A variable that has the filename stored in it may also be used. <prompt> - Either a text string or a variable name. Most of these are optional, so use them only if you want them. <relation> - Any of the following, but see the specific com- mand for verification: = Equal to <> Not equal to > Greater than >= Greater than or equal to < Less than <= Less than or equal to <option> - The value of this item is command-specific. <token#> - Any single item; see section 1.2 for a complete definition of a token. Note: If the command name is followed by a '<---' then the syntax for the command is just the command name. VSCRIPT Documentation -- 3 1.5 - Special Variables/Constants ═════════════════════════════════ The script language contains the following restricted variables, which are read-only: $AGE - Age of user. $ANSI - Stores the user's current graphics setting. Set to OFF if using ASCII, ON if using ANSI, and ENH if using PDM's. $AVAILABLE - Stores the sysop availability flag. Y if sysop is available, N if not. $BAUD - Stores the user's connect speed. Returns "" if logged into node 0 (or other local node) and returns "CONSOLE" if logged in locally from the WFC screen. $BBSNAME - Stores the BBS' name, as shown in VCONFIG. $BELL - Stores ASCII code 7, causes a beep when printed. $BIRTHDATE - User birthdate in same format as $DATE. $BS - Stores ASCII code 8, causes the cursor to back up 1 space on current line when printed. It is not a destructive backspace. $CLEAR - Stores <CTRL>-<L> for ASCII users, stores the ANSI clear screen code for others when printed. $<color> - These nine variables are reserved as color codes: $RED, $BLUE, $CYAN, $GREEN, $YELLOW, $MAGENTA, $WHITE, $BLACK, and $NORM. See section 3.3 for more information. $CR - Stores ASCII code 13, causes a carriage return when printed (moves to column 1, current line.) $CREDITS - Number of credits user has. $CRLF - Causes both a $CR & $LF when printed (moves to column 1 of the next line.) $DATE - Stores the current system date as MM-DD-YYYY. $EXTRAx - The users extra variables values are stored in $EXTRA1 thru $EXTRA8. They can be changed with the SETEXTRA command. See section 8.2 for info. $FLAGS - This contains the list of all active general flags of the current user. Use the INSTR command with $FLAG and you will know if a particular flag is on if the result is non-zero. You can change the value of a flag with the SETFLAG command. See section 8.2 for info. $HANDLE - User's handle. $LF - Stores ASCII code 10, causes a linefeed when it's printed (same column position, next line.) $MAXTIME - Maximum minutes per day. $NAME - User's real name. $NODE - Stores your VirtualNET node # as set in VCONFIG. Default is 0 if you are not in VirtualNET. $PAGE - Number of lines to print before pause. $PORT - Returns present channel # of user (not COM port!) $SECURITY - User's security level, 250 and up is considered Co-sysop/Sysop access. Use TESTVAL and this variable to implement your own security. VSCRIPT Documentation -- 4 $SYSOP - Stores the sysop's name as set in VCONFIG. $TEXTPATH - Stores the path to your TXT directory. $TIME - Stores the current system time. $TIMELEFT - Number of minutes left for this session. $TIMEON - Number of minutes on for this session. $TIMESON - Total number of logons for the user. $TOTALMIN - Total number of minutes on since first logon. $USER - User's account number. $VIDEOMODE - This stores values similar to $ANSI, only they are #'s instead of words. Set to 0 if using ASCII, 1 if using ANSI, 2 if using PDM's, and 3 if using VGIX. 1.6 - Interfacing with VBBS ═══════════════════════════ There are only two ways that you can run a script. You can either run the script from a function block or LINK to it from another script. The former is covered here and the latter is covered in section 7.3 - Passing Control. Go into the function block you wish to have run the script and add the following line on any but the first two lines in the .FB file: Z 001 2 Scripter | | | ^------This is the script name, NO extension. | | ^----------This is the code to tell VBBS it is running a | | script | ^-------------This is the SL to be able to use the key (and | run the script.) ^----------------This is the key to press at the menu to load and run the script. 1.7 - Prepackaged Scripts ═════════════════════════ --> IMPORTANT NOTE: This section is best read after reading through the entire file but is included here to maintain the structure of this document. Do not let the unknown terms interfere with your reading, as they will all be explained elsewhere. There are many script authors out in the BBSing community that have written all sorts of scripted programs to perform prac- tically everything you could ever want. The most difficult part of using a script is knowing how to install it. What you should do first is pull up the script and look for comments that explain the script. Some will contain complete sets of instructions, while others will contain no comments at all. If the script con- tains few or no comments, then what you will need to do is: VSCRIPT Documentation -- 5 1> Make sure that all EXIT and LINK statements point to FB's or scripts that you actually have. If all else fails you can set all of these statements to EXIT to your main FB file (see VBBS.DOC for information.) 2> Look for any statements that use file commands. Be sure to change these to valid paths on your system. 3> See if the script has any RET lines. If it does, try to find the CALL statements to the labels that appear a few lines before the RET. After you have done these steps you will then have the info you need to determine how the script should be used. If the script has no EXIT or LINK statements, or the script has a RET line with no CALL statement, then you must make the script part of an exis- ting one. The easiest way to do this is to just block-copy the entire script in before your final EXIT or LINK statement in your script if it has no unmatched RET statements. If there is an unmatched RET statement, then installing the new script is even easier. Somewhere in your script you need to add a CALL <label> statement with <label> being the label at the start of the new script. Then just add as the last line of your script the line '& <script name>'. You should be able to compile and run it at this point. Just remember, 'Nothing is Guaranteed!', so if you have a problem with a script and you can't get it to work try to either pick the code apart (if you can) or hop onto any VirtualNet BBS that carries a script dis- cussion sub and ask a few questions (or a few hundred, as needed.) One of the script gurus may be able to help you out, and you might even be able to get in touch with the author. VSCRIPT Documentation -- 6 ╔════════════════════════════════════════════════════════════════╗ ║ (2) NUMBER AND STRING HANDLING ║ ╚════════════════════════════════════════════════════════════════╝ 2.1 - Numeric Operators ═══════════════════════ VSCRIPT supports the following mathematical operators: + Addition - Subtraction * Multiplication / Division ^ Exponentiation All math commands in the script language are performed from left-to-right. Parentheses can NOT be used in a formula, so any math that needs to be done in a hierarchical format must be done over more than one line. Also, remember the restriction on 'tokens' - a math symbol counts as a token, so only two math operations can be performed on one line. Example: Results: $a= 2 * 2 + 4 => 4 + 4 => 8 $b = $a + 2 / 5 => 10 / 5 => 2 $c = $b + 5 - 4 => 7 - 4 => 3 $d = 4 / $b ^ 3 => 2 * 2 * 2 => 8 2.2 - Numeric Functions ═══════════════════════ INT 0 -> <variable1> = <value2> INT 0 This function takes the number stored in <value2> and rounds down to the next lower whole number. The resulting integer is then stored in <variable1>. Remember: negative numbers also round down with this function as shown below: $total = -11.25 INT 0 returns a value of -12, not -11. SQR 0 -> <variable1> = <value2> SQR 0 This function returns the square root of the absolute value of the number stored in <value2>. The result is then stored in <variable1>. Note: The absolute value of a number equals its positive value, ie absolute of -11 = 11. RND -> <variable1> = <value1> RND <value2> This function generates a random number between the two <value>'s. If <value1> is smaller than <value2> then the result will not include either number. If <value1> is larger than <value2> then the result can include either number. VSCRIPT Documentation -- 7 Example: Results: $a = 4.15 * 4 + .25 => 16.85 $b = $a INT 0 => 16 $c = $b SQR 0 => 4 $d = $a INT 0 SQR 0 => 4 $e = $b RND $c => a random number from 4 to 16 $f = $c RND $b => a random number from 5 to 15 2.3 - String Operators ══════════════════════ & -> <variable1> = <token3> & <token5> & <token7> This allows you to link together many variables and strings to print as a single variable, effectively adding many tokens together. ex: $Junk = "This is" & " one big " & "statement!" 2.4 - String Functions ══════════════════════ In addition to the '&' operators there are some functions for use with strings and variables that store strings. ASC 0 -> <variable1> = <string2> ASC 0 This function finds the ASCII code of the first character in <string2> and stores it in <variable1>. CHR 0 -> <variable1> = <value2> CHR 0 This function takes <value2> and places the character with the matching ASCII code into <variable1>. LEN 0 -> <variable1> = <string2> LEN 0 This function returns the number of characters within <string2> and places the result in <variable1>. UPPER 0 -> <variable1> = <string2> UPPER 0 This function returns the upper case equivalent of what is in <string2>. It only changes the lower case letters, leaving all numbers and symbols as they are in the original <string2>. INSTR -> <variable1> = <string2> INSTR <string3> This function scans <string2> to see if <string3> exists within it. It returns a 0 to <variable1) if it is not found, otherwise it returns the position of <string3>. VSCRIPT Documentation -- 8 MID -> <variable1> = <string2> MID <value3> LEFT -> <variable1> = <string2> LEFT <value3> These functions return portions of a string. MID starts at the character <value3> and returns the rest of the string. LEFT starts at the left-most character and returns a number of characters equal to <value3>. Example: Results: $a = "aBc2" & "05 D" & "e╫Fg" => "aBc205 De╫Fg" $b = $a MID 10 => ╫Fg $c = $b ASC 0 => 215 - the ASCII code for ╫ $d = $a LEFT 6 MID 4 => 205 $e = $d CHR 0 => ═ - the ASCII 205 character $f = $a INSTR "205" => 4 - the 205 is in the string and the 2 is located in the 4th position. $g = $a LEN 0 => 12 $h = $a UPPER 0 => "ABC205 DE╫FG" Note: The quotes in the strings are not an actual part of the strings. They are there only to denote the beginning and end of a single token. 2.5 - String Alterations ════════════════════════ There are a few commands that actually allow you to alter the format of a variable. All of them use the same syntax and are described below. JC -> JC <variable1> <value2> JL -> JL <variable1> <value2> JR -> JR <variable1> <value2> These commands all take what is stored within <variable1> and pad it with extra spaces. JC centers the <variable1> in a field of <value2> spaces. JL places it along the left margin and JR places it on the right margin in a similar field. Example: Results: $size = 14 $a = "Greed!" => $a now has the value: JC $a $size " Greed! " $b = "Green!" => $b now has the value: JL $b $size "Green! " $c = "Groan!" => $c now has the value: JR $c $size " Groan!" VSCRIPT Documentation -- 9 ╔════════════════════════════════════════════════════════════════╗ ║ (3) INPUT AND OUTPUT COMMANDS ║ ╚════════════════════════════════════════════════════════════════╝ 3.1 - Reading Input ═══════════════════ One of the most common uses of a script is to get some information from a user and the script language contains many commands to help implement this task. All the commands allow for a <prompt> string, but this is optional so you do NOT have to use it if you do not want to. GETYN -> GETYN <variable1> <prompt> GETNY -> GETNY <variable1> <prompt> These two commands show the user whatever is stored within the <prompt> and ask for a response of Y, N, or <enter>. The GETYN command defaults to Y when then user presses <enter> and GETNY defaults to N. ex: GETYN $yesorno "Do you wish to continue ? " RS -> RS <variable1> <prompt> This command prints the optional <prompt> and then accepts a line of input. The input can be no more than 81 characters in length, and input is terminated by pressing <enter>. ex: RS $yourname "What is your name ? " RX -> RX <variable1> <prompt> This command works like the RS command but instead of it echoing the keys that the user presses it prints X's. This is very useful for password systems. RW -> RW <variable1> <prompt> This command works like the RS command with the only real difference being that this command has a word-wrapping feature. If a word passes the 80 character point it is word-wrapped over to the next input line. To prevent the extra characters from being placed into the next input statement you will need to place 'Buffer Clear' after the last RW input line. See section 5.x for more info on buffer commands. RN -> RN <variable1> <prompt> This command prints the optional prompt and then accepts only numerical input. It will not take any keys but the #'s and input is terminated by pressing <enter>. ex: RN $number "Enter your favorite number : " VSCRIPT Documentation -- 10 RC -> RC <variable1> <prompt> This command prints the optional <prompt> and then waits for a single character to be pressed. The character is stored in <variable1> but it is not shown on the screen. ex: RC $onechar "Pick a key, any key : " RR -> RR <variable1> <string2> <prompt> This command operates in the same way as the RC command with only one difference. It will only accept characters that are listed in the <string2>, all others will be ignored. ex: RR $thisone ARI "A>bort, R>etry, I>gnore ? " RL -> RL <variable1> <string2> <value3> <prompt> This command operates similarly to the RR command. It will accept any character listed in <string2> and also will accept a number between 1 and <value3>. This is the most versatile form for getting input, and is most commonly used for creating a menu within a script. ex: RL $thatone ABC 3 "Choose A, B, C, 1, 2, or 3 : " RF -> RF <variable1> <prompt> This command is used to get a filename as input. It will only accept input in the format 'xxxxxxxx.xxx' with each 'x' being a character. It will only allow legal characters for the name and it will not accept globals (* and ?.) The complete list of acceptable characters contains A thru Z (uppercase is forced automatically) and the symbols => ! # $ _ - (the => is not in the list, it is used only for emphasis.) ex: RF $filename "Name of file to be uploaded : " RI -> RI <variable1> <prompt> This command is nearly identical to the RF command. The one difference being that this command accepts the * and ? globals in the filename. ex: RI $filetoget "Name of file to find (* and ? allowed) : " 3.2 - Showing Line Output ═════════════════════════ There are two different ways that you can show output one line at a time. While they are slightly different, both accept the same formatting information for their output. TR -> TR <token2> <token3> <token4> ... <token7> TS -> TS <token2> <token3> <token4> ... <token7> These commands can print out up to 6 different tokens using a single line. After the last token on the line is printed the VSCRIPT Documentation -- 11 TR command performs a carriage return/linefeed while the TS command does not. The three formatting statements are listed below. %s -> %s<number1> <variable2> Outputs <variable2> in a field of <number1> spaces and then left justifies it. %i -> %i<number1> <variable2> Outputs <variable2> in a field of <number1> spaces and then right justifies it. %d -> %d<number1>.<number2> <value3> Outputs <value3> with the format ###.## where <number1> and <number2> are the ### and the .## respectively. The left part of the output is padded with spaces and the right is padded with 0's. This format uses the absolute value of <value3>, so the output is always a positive number. You can use any numbers within the statements as long as you follow the specified syntax. If the field selected is too small for the variable then the output will be chopped down to fit it into the field. Example: Results: $a = "Green" $b = 16.2312 tr $b " : " %d3.3 $b => "16.2312 : 16.231" tr %s10 $a ":" %i10 $a => "Green : Green" ts $b " : " tr $a " : The End" => "16.2312 : Green : The End" Note: The quotes are not in the actual output, they are only supplied to emphasize the blank spaces. 3.3 - Colorization ══════════════════ There are three different ways to change color in the script language. All are identical in output, but each has a unique form of implementation. Note: <color code> is the number (0-9) or letter (capital A-Z) code that corresponds to the colors as listed in the COLORS.TXT file. Also, the input commands from section 3.1 (RS, RW, RX, etc.) will all change the color to the user's default prompt setting unless the <prompt> has a color code within it. VSCRIPT Documentation -- 12 ANSIC -> ANSIC <color code> This command is executed on a line by itself and changes the effective color to that of the selected <color code>. $<color> -> Special The $color commands are actually individual tokens that resemble variable names. As such, they may be included into other strings with the '&' command (section 2.3) or used on their own in output statements (TR & TS.) $<color> color code $<color> color code -------- ---------- -------- ---------- $RED 6 $YELLOW 2 $BLUE 7 $MAGENTA B $GREEN 5 $CYAN 1 $WHITE U $NORM 0 $BLACK n/a The command $BLACK makes very dark letters though they may be visible, depending on your system configuration. A common use for this is to cover over ANSI music symbols. Hearts -> Special The most frequently used way to change colors is to use what has been coined 'Heart-code ANSI.' The Heart code is the ASCII code 3 and can be created in a couple of different ways. If your ANSI driver supports the extended ASCII character set you can create the 'heart' by pressing the <CTRL> key and the <C> key or it can be made by holding down the <ALT> key, then press 3 (or 003 or 259) on the number pad and then releasing the <ALT> key. You will have to test this for your particular system to see which works for you. You can also create the codes by using the full-screen editor to colorize although this can be a bit of work. Immediately after the 'heart' you place the desired <color code> and when the script actually runs, VBBS will show the correct color (you will not see the 'heart' or the next character after it.) Example: These -----\_______/ANSIC 6 three | \TR "Hello ! " $handle pieces | of code |_______/$stuff = $red & "Hello ! " & $handle all do | \TR $stuff the exact | same thing-/-------<TR "<heart>6Hello ! " & $handle VSCRIPT Documentation -- 13 3.4 - Other Display Commands ════════════════════════════ EF -> EF <pathfile1> This command displays the contents of the specified file in <pathfile1>. It will pause whenever the users screen fills and continue when a key is pressed. DRAWWAITBAR -> DRAWWAITBAR <value1> This command draws a string of green o's surrounded by red []'s. The number of o's is equal to <value1>. The cursor is then placed on the first 'o' so you can write over it with another character. See Appendix D for an example. LOC -> LOC <value1> <value2> This command places the cursor at the location equal to the (x, y) coordinates that match (<value2>, <value1>). Legitimate values for <value1> are 1-25 and for <value2> are 1-80. This only operates for users of ANSI, Enhanced ANSI, and VGIX. MENU -> MENU <filename1> This command displays a menu file stored in your text directory (as set in VCONFIG.) VBBS first checks to see if <filename>.MNU exists, and shows it if true. Otherwise it shows <filename>.ANS if the user has ANSI and <filename>.ASC otherwise. The .MNU files are universal text files colorized with VBBS' heart-code ANSI colors. If the user has ANSI then the file displays w/ the colors, but if the user does not have ANSI then it is displayed without the colors. You can still use .ANS and .ASC menus if you like, however. If ! is the first character of a line in a menu then VBBS will only show the line if the user's security level is greater than or equal to the three-digit number that follows the '!'. Examples: !255 S) SysOp Menu <== Not shown unless the user has SL >= 255. !100 F) Forward <== " " " " " " " >= 100. NEWPAGE <--- SUSPENDPAGEBREAK <--- RESUMEPAGEBREAK <--- These three commands alter the user's page-break pointer. This pointer determines how many lines of text have been viewed and the user's screen length (as set in defaults) determines when a pause should be used. NEWPAGE resets the pointer to 0 VSCRIPT Documentation -- 14 so the output will scroll for a number of lines equal to the value set in the user's defaults. SUSPENDPAGEBREAK turns the use of the pointer off completely (no pauses at all), while RESUMEPAGEBREAK turns the pointer back on. PAUSE -> PAUSE <prompt> This displays the optional <prompt> or the default prompt as set in VCONFIG. It then waits for a keypress and erases the prompt before continuing. VSCRIPT Documentation -- 15 ╔════════════════════════════════════════════════════════════════╗ ║ (4) DATABASE OPERATIONS ║ ╚════════════════════════════════════════════════════════════════╝ Each database (DB) in VBBS can be used in many different ways for storing info. A DB can store normal messages, file descriptions, or even messages with attached files. Also, there is no reason why you can't redefine the fields and use them for other types of data storage, like a special voting booth or customized daily news section. Each DB entry is made up of two parts - The Header and the Memo Section. The Header contains things like the subject, the sender's name, addressee, etc. The Memo Section is the actual body of the entry. The body, while always text, may contain either a standard message or a long file description, depending on how you are using the database. 4.1 - Database Selection ════════════════════════ Before you can implement any database commands you must first select the exact database you wish to use. This is done with the commands DBGROUP and DB. You must use the commands in the order shown for proper results. DBGROUP -> DBGROUP <group identifier> This selects the database group that you will be using in the script. The <group identifier> is the letter representing the DBG as it appears in VCONFIG. See VBBS.DOC for more info. ex: DBGROUP A <-- This makes DBGroup A the active area. Before you can select a database to use, you must first select a database group. Grouping was implemented so that it would be much easier to implement global functions and so that databases may be added and deleted (using VCONFIG.EXE) without the need to edit the scripts every time. The <group identifier> is a single alphabetic character (from A to Z) and you can set your database groups up any way you like. A common set of DB Groups might be: <A> Public message bases <H> Hidden/restricted message bases <F> Public file bases <I> Hidden/restricted file bases <O> Special bases like voting sections, daily news, etc. The following read-only variables are loaded when you execute the DBGROUP command: -------------------- $DBNUMBER - Stores the total number of databases in the selected group. The lowest numbered DB in a group is always a 1, so this number supplies the upper limit for loop operations within a database group. VSCRIPT Documentation -- 16 $DBGROUP - This stores the letter you selected on the DBGROUP command line. Note: This variable is not cleared when you LINK to another script (see section 7.3), so this can be used to keep track of your location. -------------------- DB -> DB <database number> The DB commands sets the current database for use. You must select a database using this command somewhere in your script before any of the other database commands (except DBGROUP) are used. Once you set the database, it stays set until another DB command is executed. Also, the database must have been defined previously using VCONFIG.EXE. The following read-only variables are loaded when you execute the DB command: -------------------- $DB - This stores the database number you have selected. Like $DBGROUP it is not cleared when you LINK between scripts and so using the two variables you can maintain a constant position within your DBs. $DBNAME - The long name of the selected database. $DBPATH - The path (if any) in the 'File Path' section of the VCONFIG Database entry. $DBFILE - The filename of the actual database storage file. $HIGHDB - This is the pointer that stores the number of the user's highest-read entry in the database. $NUMBERDB - This stores the total number of entries in the database. $WRITESL - This contains the minimum security level needed to write to the database. -------------------- 4.2 - LOAD Related Commands ═══════════════════════════ The next few commands are all used to manually load in a database entry for display and/or analysis. LOAD -> LOAD <value1> <option> This command loads the database entry <value1> and has one command <option>. Adding /Q to the command line will set it so the user's $HIGHDB pointer is not updated. The command also loads the following variables: -------------------- $ATTFILE - Filename of a file that is attached to the message, if any. $DBCOUNT - This variable starts at 0 and can be increased by using the ADDCOUNT command (see section 4.3). It can not be decreased and has one value for each DB (not for each individual message or file.) VSCRIPT Documentation -- 17 $DBDATE - Creation date and time of the entry. $DBFLAG - The value can have a value of 0 or 1 and can be toggled with the DBFLAG command (see section 4.3). The value of this variable is constant, so if it is turned ON it is treated as ON for all users who access the message/file affected. $FROM - The handle of the person who created the entry. $FROMNO - The user # of the person who created the entry. $FROMNODE - VirtualNET node number of sender. $SIZE - Size of attached file, set to 0 if none. $SUBJECT - The subject of the message, or brief description for a file entry. $TO - The handle of the addressee, if any. $TONO - The user # of the addressee, 0 if to ALL. $TONODE - VirtualNET node number of addressee. $RESULT - This variable contains one of these items: DEL if <value1> is marked for deletion OUT if <value1> is greater than the number of available entries (listed in $NUMBERDB) PRI if the DB is private and the user is not the sender, addressee, or has an SL below 250 (ie Sysop or CoSysop) OK in all other cases -------------------- DISPLAYMSG <--- This command displays the message header info to the user. It will clear the screen before showing this info if the user is using enhanced ANSI (see VBBS.DOC for more information.) DISPLAYTEXT <--- This command displays the memo section of the message to the user. It clears the screen like DISPLAYMSG for enhanced ANSI users. 4.3 - Editing Commands ══════════════════════ All of these commands operate independently of the LOAD command. They do still require you to select a DBGROUP and DB before use, however. ADDCOUNT -> ADDCOUNT <value1> This command increases the number stored in the $DBCOUNT by 1 if <value1> is a positive number. VSCRIPT Documentation -- 18 CLEANUP <--- This performs the PACK function (below) on all databases. This command does not require the use of the DBGROUP or DB commands before use. DBFLAG -> DBFLAG <value1> <switch> This command toggles the value stored in $DBFLAG for the entry <value1>. The valid switches are ON or OFF and the matching $DBFLAG values are 1 and 0, respectively. DEL -> DEL <value1> This command marks the entry <value1> for deletion. It also returns the $RESULT variable with the possible values being OUT, PRI, and OK (see LOAD entry above.) PACK <--- This command deletes all messages within the selected DB that have been marked for deletion and then resequences the database. All user and network pointers are automatically updated to show the change in message numbers. QS -> QS <value1> Manually set the user's $HIGHDB pointer to <value1>. If <value1> exceeds the value in $NUMBERDB then $HIGHDB is set to equal $NUMBERDB. SAVE -> (command on next line due to length) SAVE <value1> <value2> <string3> <value4> <filename5> <value6> This command makes a database entry and saves it in the current database. The variables used are: -------------------- <value1> - This is the user # that the message is addressed to, this should be set to 0 if to ALL. <value2> - This is the network address of the addressee, use $NODE if the addressee is local. <string3> - This will be the $SUBJECT of the saved message. <value4> - This contains the size of the attached file, use 0 if none. <filename5> - This is the name of the attached file, use "" if none. <value6> - This is the network ID of the addressee, use 1 if the addressee is local. -------------------- The message saved uses the above information to create the header and then takes the contents of the buffer and uses it as the main body of the message. See section 5.x for information on how to use the buffer. This command can not be used to send files attached to emails, it can only be used to add files to a database listing. VSCRIPT Documentation -- 19 SEARCH -> SEARCH <value1> <number2> <string3> This command searches the contents of the database for <string3> starting at the entry <value1>. The search is case insensitive on <string3>. The value for <number2> can be any of the following: 2 - Search the FROM field, <string3> is not used here as it will always search for the current user's handle. 3 - Search the SUBJECT/TITLE field, <string3> can be any word or group of words. 5 - Search the FILENAME field, <string3> must be an acceptable DOS filename with no wildcards. This command also returns two variables: -------------------- $RESULT = OUT if <string3> is not found, OK if otherwise. $SEARCH = the entry number where <string3> was found. -------------------- 4.4 - Viewing & Writing ═══════════════════════ ╔════════════════════════════════════════════════════════════════╗ ║** Note:All commands marked with a (*) before the description **║ ║** will only work properly if implemented from within **║ ║** a script that was called from a function block that **║ ║** has DBGroup(s) listed in it. They take the letters **║ ║** for the DBGroups to use from the second line of the **║ ║** .FB the script was called from. The DBGROUP and DB **║ ║** commands do not affect any of these commands. **║ ╚════════════════════════════════════════════════════════════════╝ These commands allow the user to view messages and move around within your databases. CHOOSETOPIC <--- (*) This command lists all the DBGroups (also known as topics) and allows the user to switch over to a different one. The user can also view an index of all databases available from within this option. LISTBASES <--- (*) This lists all the DB's in the current DBGroup. NEXTBASE <--- PREVBASE <--- These commands move to the next or previous database within the selected DBGroup, respectively. VSCRIPT Documentation -- 20 POST <--- This lets the user to enter a message into the active DB. READSEQMSG <--- This command allows the user to read the messages within the current database. It also contains a search feature. READNEWMSG <--- This starts the user's new message scan, showing all new messages in databases that are in the user's quick-scan list. SCANMSG <--- This command brings up a summary of the messages in the selected database. The user can select a message to read from this listing and has access to all sub-menu commands while reading the messages. SELECTBASE <--- (*) This command lists all the bases and then allows the user to select a different DB as the current one. The user can also switch to a different DBGroup with this command. SETQUICKSCAN <--- (*) This command allows the user to select what databases he or she would like to view during a new message scan. 4.5 - E-mail Functions ══════════════════════ The E-mail section of the database structure is a separate entity. To make it the active database for using the SAVE and BUFFER commands you need to execute the following command: SETEMAIL <--- This command is used instead of the DBGROUP & DB commands to make the e-mail section the active database for use with BUFFER and SAVE (see sections 5.x and 4.3, respectively.) FEEDBACK <--- This brings up the multi-feedback list (see VBBS.DOC) and prompts the user to send a message to the sysop. VSCRIPT Documentation -- 21 QUICKMAIL <--- This brings up the multi-mail menu for sending e-mail to a group of people all at once. READALLEMAIL <--- This is a sysop command that allows you to read all E-mail currently in the system. READEMAILFROM <--- READEMAILTO <--- These commands allow the user to read all the E-mail FROM them or addressed TO them, respectively. SENDEMAIL <--- This command allows the user to send E-mail to other users. VSCRIPT Documentation -- 22 ╔════════════════════════════════════════════════════════════════╗ ║ (5) BUFFER OPERATION & USE ║ ╚════════════════════════════════════════════════════════════════╝ In order to accommodate larger memo sizes VBBS uses a disk file buffer in the format Bx.TMP, where x is the channel number that the user is on. This file is stored in the \VBBS dir. The commands used to access the buffer are listed below. BUFFER APPEND -> BUFFER APPEND <string1> This adds <string1> to the present buffer. BUFFER CLEAR <--- This erases the contents of the present buffer. BUFFER EDIT <--- This command loads up the user's selected editor and puts the current contents of the buffer into it. Note: When using the full-screen editor the user can edit, add, or clear the buffer. The line editor will only allow you to add lines to the current buffer or clear it. The user can clear the buffer by aborting out of either editor. BUFFER LIST <--- This prints the current buffer contents to the screen. If the user is in ASCII mode then heart-code ANSI is not shown on screen but remains within the buffer file. VSCRIPT Documentation -- 23 ╔════════════════════════════════════════════════════════════════╗ ║ (6) FILE COMMANDS ║ ╚════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════╗ ║** Note:All commands marked with a (*) before the description **║ ║** will only work properly if implemented from within **║ ║** a script that was called from a function block that **║ ║** has DBGroup(s) listed in it. They take the letters **║ ║** for the DBGroups to use from the second line of the **║ ║** .FB the script was called from. The DBGROUP and DB **║ ║** commands do not affect any of these commands. **║ ╚════════════════════════════════════════════════════════════════╝ 6.1 - Information Commands ══════════════════════════ CHECKFILE -> CHECKFILE <variable1> <pathfile2> This command checks to see if <pathfile2> exists on your system and places the file size into <variable1>. It returns a 0 if the file does not exist. FINDFIRST -> FINDFIRST <variable1> <pathfile2> FINDNEXT -> FINDNEXT <variable1> These commands search for the file mask <pathfile2>. It may include globals and will default to the \VBBS directory if no path is specified. You must execute FINDFIRST once before you can use the FINDNEXT command. Both commands will return the full filename to <variable1> or a "" if no match is found. FINDFILES <--- (*) This asks the user for search text and asks if the user would like to search all topic areas. It then searches all the files in the selected DBGroup(s) and searches the descriptions for those that contain the search text. LISTFILES <--- This prompts for a filename (wildcards accepted) and then lists all matching files in the current database. NEWFILES <--- (*) This command asks the user would like to scan all topic areas and then lists all new files in the selected DBGroup(s). RATIO <--- This displays the user's upload/download ratio. VSCRIPT Documentation -- 24 REVIEWFILE <--- This command allows the user to review any of the files in the current database. They can they be downloaded or tagged for a batch download later. REVIEWUPLOADS <--- (*) This command allows the sysop to review all new files that have been uploaded by users. SEARCHALL <--- (*) This works like LISTFILES, but also allows the user to search all topic areas. It then lists the matching files in the selected DBGroup(s). SETNEWFILESSCAN -> SETNEWFILESSCAN <value1> This command will set the number of days back a NEWFILES scan equal to <value1>. If <value1> is left blank then the user will be prompted for the number of days to use. TOPDOWNLOADS <--- This lists the top downloads in the active file DBGroup. XFERTIME -> XFERTIME <variable1> <pathfile2> This command will calculate how long it will take to download <pathfile2> and stores it in <variable1>. It will return a 0 if the file is not found. 6.2 - Transfer Commands ═══════════════════════ BATCHDL <--- This command brings up the batch transfer menu. DLMASTERLIST <--- (*) This command allows the user to download a zipped listing of your entire transfer section. DOWNLOAD -> DOWNLOAD <pathfile1> This prompts the user to choose an xfer protocol and then sends the file <pathfile1>. VSCRIPT Documentation -- 25 DOWNLOADFILE <--- (*) This command prompts for a filename (it accepts wildcards) and then show the user the file's review screen. The user can then download directly or tag for a batch download. REMOTEUPLOAD <--- This allows the user to upload files to the BBS. SYSOPUPLOAD <--- This command allows the sysop to upload files locally. UPLOAD -> UPLOAD <pathfile1> This command prompts the user to choose a protocol and then receives <pathfile1> from the user. A full path may be used, but is not necessary. 6.3 - File Editing ══════════════════ VSCRIPT allows you to directly read and write from pure ASCII text files. The commands to do so are listed here. Note: You must always OPEN a file before performing any of the other commands and CLOSE it when done, except as noted. EDITFILE <--- This allows the sysop to edit any text file with no more than 200 lines. This is one exception to the OPEN and CLOSE rule, you should not use either with this command. CLOSE <--- This closes a file previously opened with OPEN. KILL -> KILL <pathfile1> This deletes <pathfile1> off of your system. This is the other exception to the OPEN and CLOSE rule, you should not use either with this command. OPEN -> OPEN <pathfile1> <option> This command opens a file for use. One of the following three options must be selected on the command line: INPUT -> This allows you to READ data in from a file OUTPUT -> This allows you to create a file and begin to WRITE new information into it. APPEND -> This allows you to open an existing file and WRITE information onto the end of it. VSCRIPT Documentation -- 26 READ -> READ <variable1> This will read in a single line from the file and place it into <variable1>. Multiple READ statements will continue to read in the next line in the file and if the end of the file is reached it will return an !EOF!. The only way to start at the top of a file again is to CLOSE it and then OPEN it again. WRITE -> WRITE <token2> <token3> <token4> ... <token7> This command performs exactly like the TR command in section 3.2 with the only difference being that the output goes into a file instead of on screen. VSCRIPT Documentation -- 27 ╔════════════════════════════════════════════════════════════════╗ ║ (7) CONTROL COMMANDS ║ ╚════════════════════════════════════════════════════════════════╝ 7.1 - General Redirection ═════════════════════════ # -> # <label> This command allows you to set points up within your script that the various other control commands can use. ex: TR "Hello " GO skipit TR "You wont see this text..." # skipit TR "Because you just jumped down to here!!" CALL -> CALL <label> This forces the script to go to <label> and continue to run from there. When a RET is found the script will go back to the line after the CALL command. GO -> GO <label> This forces the script to go to <label> just like the CALL command, with the only difference being that it will not return if it encounters an RET statement. RET <--- This returns a script from a routine CALLed to the line after the CALL statement. Note: RET is ignored if there was no CALL statement used. 7.2 - Loops and Comparisons ═══════════════════════════ VSCRIPT supports some of the more common forms of loops and comparison structures. These are all covered below but note that the script language can not generally handle nested loops easily, so some testing must be done before you create any scripts using such combinations. 7.21 - DO Loops ─────────────── -> DO <variable1> = <value2> <value3> [body of the loop] LOOP This type of loop begins with <variable1> equal to VSCRIPT Documentation -- 28 <value2>. Each time it reaches the LOOP it adds 1 to it and continues until <variable1> is greater than <value3>. -> DO WHILE <variable1> {must store a numeric!} [body of the loop] LOOP This type continues to loop until <variable1> = 0. You must have some way to either exit the loop, or have a place where <variable1> is set to 0 or the script will lock into an endless loop. 7.22 - IF/IFVAL Structures ────────────────────────── IF structures allow you to compare 2 strings to see if they match, valid <relation> operators are = and <> ONLY! The IFVAL structures are identical to IF structures, but they are used to compare numeric variables. Valid IFVAL <relations> are =, >, >=, <, <= and <>. -> IF <variable1> <relation> <variable2> THEN [then-code] ENDIF This performs the [then-code] if <relation> is true. -> IF <variable1> <relation> <variable2> THEN [then-code] ELSE [else-code] ENDIF This performs similar to the IF structure, but if the <relation> is false it performs the [else-code]. 7.23 - TEST/TESTVAL Commands ──────────────────────────── -> TEST <variable1> <relation> <variable2> <label> -> TESTVAL <variable1> <relation> <variable2> <label> The two TEST commands allow you to compare two variables, and if the comparison is true, to go to a separate part of the script (as if a GO <label> had been used.) The only difference in the two commands is that TEST performs a non-case-sensitive string comparison and TESTVAL performs a mathematic comparison. Valid <relations> are =, <, <=, >, >= and <>. VSCRIPT Documentation -- 29 7.3 - Passing Control ═════════════════════ There are a total of four ways that you can pass control from a script to something else. These four ways each have special uses and are covered below. Note: These commands will only accept one token following the actual command. If you wish to have more items on the line then you must place them into a variable and place the variable on the command line. ex: $doscom = "dir " & $pathused & " /w" SHELL $doscom LINK -> LINK <filename> This command causes the present script to terminate and begin running a script called <filename> (do not use any extension or globals in the filename.) All of your variables will be cleared before the new script begins operation. EXIT -> EXIT <filename> This command causes the present script to terminate and then exits to the function block <filename> (as with LINK, do not use extensions or globals.) If no <filename> is specified then the script will exit to the .FB file that it was called from UNLESS the script did a shrinkout (see DOOR, below) in which case it will always exit to START.FB. SHELL -> SHELL <pathfile or DOS command line> This will drop to DOS while keeping the BBS in memory. It will then execute the command following SHELL and then return to the line after the SHELL command. All of your variables are retained because the script is never taken from memory. DOOR -> DOOR <pathfile or DOS command line> This will shrink the BBS out of memory and drop to DOS. Implementation of the DOOR command writes the dropfiles CHAIN.TXT, DOOR.SYS and DORINFOx.DEF to disk. If nothing else is specified on the command line then the script will bring up your list of Doors as set in VCONFIG, otherwise it will execute the required command line. All of the script variables will be cleared by the DOOR command. After the DOOR has been exited the user will return to the function block that the script was called from unless one of the following two commands are used just before the line that contains the DOOR command: VSCRIPT Documentation -- 30 RETURNFB -> RETURNFB <function block name> RETURNSCRIPT -> RETURNSCRIPT <script name> If either of these two commands precedes the DOOR command the user will be returned to the function block selected OR the beginning of the selected script. If an invalid function block name or script name is given it will restore the user to the START.FB function block. If you do not have a START.FB then the BBS will shut down. VSCRIPT Documentation -- 31 ╔════════════════════════════════════════════════════════════════╗ ║ (8) MISCELLANEOUS COMMANDS ║ ╚════════════════════════════════════════════════════════════════╝ This is the catchall category. Many useful commands are located in this section that just can't be qualified by a major type. 8.1 - Visual/Interactive ════════════════════════ AUTOPOST <--- This brings up the autopost listing. See VBBS.DOC for more information on autoposts. LISTCALLERS -> LISTCALLERS <value1> This command brings up a list of the callers to your BBS for the day. This will show all of the daily callers if <value1> is left blank or set to a number higher than the total number of callers, otherwise it will show the last <value1> callers. LOGOFF <--- LOGOFFYN <--- These two commands show the user the LOGOFF.MNU and then log the user off of the BBS. The only difference between the two is that LOGOFFYN prompts the user, while LOGOFF just does it. PAGESYSOP <--- This pages the sysop for chat, if available. See VBBS.DOC for information on chat availability. RANDOM <--- This command shows one of your random blurbs from your random blurbs file. See VBBS.DOC for more information on the random message setup (in VCONFIG). STACK -> STACK <variable1> This command takes the string in <variable1> and places it into the next input section that the script enters. This can help make automating multi-keypress functions, like viewing a certain message, easy. It has been tested and can store at the LEAST 800 characters from 80 '&'ed variables with NO problems. To STACK more than one line of characters for this command just use the '&' operator to add multiple variables into the one <variable1> for use on the STACK line. If you DOOR out of VBBS or switch to VQWK/VBBS-AUX the information in the stack will be lost and will not be implemented. VSCRIPT Documentation -- 32 SYSINFO <--- This shows the user a listing of the BBS' activity during the current day and over the BBS' lifetime. VALIDATE <--- This loads up the network message validation routine. All messages in 'Validate On' subs are located here. WHO <--- This command lists who is currently online and what they are doing. This normally lists the last function block command that was selected or the last ACTION command that was used. 8.2 - User Modifiers ════════════════════ ACCOUNT <--- This brings up the user's default settings and allows the user to change them. ACTION -> ACTION <string1> This command changes the setting in the <who> command's listing to <string1>. <string1> can be a maximum of 22 characters long. ADDCREDITS -> ADDCREDITS <value1> This command adds a number of credits = to <value1> to the users account. <value1> can be positive or negative. ADDTIME -> ADDTIME <value1> This command adds a number of minutes equal to <value1> to the users time left for the day. <value1> can be positive or negative. Note: The change is for the current call ONLY when <value1> is positive but lasts for the entire day if <value1> is negative, so be careful when using a negative value. SETACCFLAG -> SETACCFLAG <variable1> <option> These are the flags used in VConfig to set up restrictions on your subs. They are the (h) flags in the user editor and more information on their uses can be found in VBBS.DOC. The <variable1> can be any letter from A to Z and <option> is either ON or OFF (remember it is case insensitive). VSCRIPT Documentation -- 33 SETEXTRA -> SETEXTRA <value1> <string2> There are 8 user-specific variables available for use. Each variable can contain a <string2> of up to 16 characters. The <value1> determines which $EXTRAx will be set. This is one of the ways you can have info pass between scripts and kept track of during the 'DOOR' command. See VDOOR.DOC for a full explaination on how this is done. SETFLAGS -> SETFLAGS <variable1> <option> There are 26 user-specific flags available for use, these are also called general (i) flags. Each flag is a letter from A to Z and they are toggled with the <option> ON or OFF. This is another way info can be passed between scripts or saved for use after a 'DOOR' command. See VDOOR.DOC for an integrated example on how this is done. Special Note - three of the flags have a preset use for VBBS: A --> This flag is toggled on/off with the defaults A>utopost command. F --> When this flag is ON the user will use the built-in Full-Screen Editor. X --> When this flag is ON the user will only see a menu by pressing <?>. Also called expert mode. SETSL -> SETSL <value1> Use this command to alter a users security level as shown by the $security variable. The <value1> can be any integer value from 0 to 250. The limit of 250 was set for security reasons. SETTIMELIMIT -> SETTIMELIMIT <value1> This command can be used to increase or decrease a user's maximum time per day as shown by the $maxtime variable. It will accept any integer from 0 to 240 for <value1> and this value is in minutes per day. The limit of 240 was set for security reasons. USEREDIT <--- This command loads the user editor, mostly for sysop use. Only accounts with an SL of 255 can access this feature. 8.3 - Real Miscellany ═════════════════════ ! -> ! <put your comments here> Comment line. All text after a '!' is ignored by the script compiler. VSCRIPT Documentation -- 34 & -> & <filename> This is an include directive for the VSCRIPT compiler to add in the contents of another script onto the end of the existing code during compilation. This allows you to write up modular scripts and use them in more than one main script without having to type or block-copy the section in. Just remember that it adds the code onto the END of the original script, so you must include the GO or CALL statements to get access to the extra sections. You can also use this function to reduce the size of a single script, as a very long START.V can cause problems when it is run (yet you will have none of the problems if you break into pieces and include them in.) BEEP <--- This sends a beep through the computer speaker. DELAY -> DELAY <value1> This command pauses the script for <value1> seconds. LOG -> LOG <token2> <token3> <token4> ... <token7> This command writes up to 6 tokens into the daily log file BBS.LOG, located in your \DATA directory. VSCRIPT Documentation -- 35 ╔════════════════════════════════════════════════════════════════╗ ║ APPENDIX A -- VGIX COMMANDS ║ ╚════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════╗ ║ Note: VGIX Commands have no effect when the user is not in ║ ║ VGIX mode. ║ ╚════════════════════════════════════════════════════════════════╝ CLS <--- This command clears the user's screen. COLOR -> COLOR <color> Set the current color for text and graphics. LINE -> LINE <x> <y> <x2> <y2> <color> <boxflag> This command draws a line or box on the user's screen, starting at point <x>,<y> to point <x2>,<y2> using the <color> specified. If <boxflag> = 0 a line is drawn, if <boxflag> = 1, a box is drawn. ╔════════════════════════════════════════════════════════════════╗ ║ Note: <x> and <x2> have an allowable range of 0 to 639. ║ ║ <y> and <y2> have an allowable range of 0 to 479. ║ ║ <color> is one of the following: ║ ║ 0=Black 1=Blue 2=Green 3=Cyan ║ ║ 4=Red 5=Magenta 6=Brown 7=Grey ║ ║ 8=Dark Grey 9=Light Blue 10=Light Green 11=Light Cyan ║ ║ 12=Light Red 13=Light Magenta 14=Yellow 15=Bright White ║ ╚════════════════════════════════════════════════════════════════╝ PLOT -> PLOT <x> <y> <color> Set the pixel at <x>,<y> using the <color> specified. CIRCLE -> CIRCLE <x> <y> <radius> <color> Draw a circle, with an origin at <x>,<y>, using the <radius> and <color> given. Allowable ranges for <radius> are 1 to 639. PAINT -> PAINT <x> <y> <color> <bordercolor> This command paints an area starting at point <x> <y> using <color>. <Bordercolor> specifies the color at which painting should stop. You would typically use CIRCLE, LINE (in box mode), or PLOT to 'outline' the shape you wanted paint to paint, and then you would use PAINT to fill your shape with color. VSCRIPT Documentation -- 36 DRAW -> DRAW <actionstring> <Actionstring> refers to a string of characters: An example might be "U4RU2R5D10L20" This would draw moving the "pen" UP 4, RIGHT 1, UP 2, RIGHT 5, DOWN 10, LEFT 20. <actionstring> commands: U Up D Down R Right L Left PLAY -> PLAY <musicstring> This command plays music on the remote user's computer. When used with high (fast) tempos, it can also be used to make sound effects. No special sound/music hardware is required. <Musicstring> refers to a string of text such as: "ABCDEFGO4L4T100" = Notes A thru G, go to Octave 4, note Length 1/4, Tempo 100. <musicstring> commands: A-G Notes A thru G O Set Octave (1 to 5) L Set Length (1 to 255 representing 1/1 to 1/255) T Tempo (1 to 255, 1=Slow, 255=Extremely Fast) + Sharp (Eg "A+" would play A sharp) - Flat (Eg "A-" would play A flat) ICONIFY <--- This command resets the VGIX ICON "counter." ICON -> ICON <iconname> <x> <y> <orflag> <key> <caption> This command displays a VGIX Icon on the user's screen. <Iconname> is a 12 character icon name. <X> and <y> are coordinates on the screen where icon is to be displayed. <Orflag>: 0 = SET ICON, 1 = OVERLAY ICON (over a background) <Key> refers to the keystroke to return if this icon is selected by the user via the mouse. <Caption> refers to the text to be printed under the icon. Captions are automatically centered beneath the icon. Note: If key and caption are absent, the icon is NOT "counted" and is not mouseable. Both key and caption must be present for the icon to be mouseable. VSCRIPT Documentation -- 37 ╔════════════════════════════════════════════════════════════════╗ ║ APPENDIX B -- PROGRAMMER'S REFERENCE GUIDE ║ ╚════════════════════════════════════════════════════════════════╝ This guide is a collection of the command formats for all the commands contained in the Virtual Script Language. If you need more detail on a command all you need to do is look in the corresponding section in the VSCRIPT.DOC. All the commands are listed in the exact same format in both places so you may also do a text search for the command line. Make sure that you read sections 1.4 and 1.5 for a listing of the format definitions and the list of restricted variables. ═════════════════════════════════════════════════════════════════ Section 2.1 - Numeric Operators ═══════════════════════════════ + - * / ^ Section 2.2 - Numeric Functions ═══════════════════════════════ INT 0 -> <variable1> = <value2> INT 0 SQR 0 -> <variable1> = <value2> SQR 0 RND -> <variable1> = <value1> RND <value2> Section 2.3 - String Operators ══════════════════════════════ & -> <variable1> = <token3> & <token5> & <token7> Section 2.4 - String Functions ══════════════════════════════ ASC 0 -> <variable1> = <string2> ASC 0 CHR 0 -> <variable1> = <value2> CHR 0 LEN 0 -> <variable1> = <string2> LEN 0 UPPER 0 -> <variable1> = <string2> UPPER 0 INSTR -> <variable1> = <string2> INSTR <string3> MID -> <variable1> = <string2> MID <value3> LEFT -> <variable1> = <string2> LEFT <value3> Section 2.5 - String Alterations ════════════════════════════════ JC -> JC <variable1> <value2> JL -> JL <variable1> <value2> JR -> JR <variable1> <value2> VSCRIPT Documentation -- 38 Section 3.1 - Reading Input ═══════════════════════════ GETYN -> GETYN <variable1> <prompt> GETNY -> GETNY <variable1> <prompt> RS -> RS <variable1> <prompt> RX -> RX <variable1> <prompt> RW -> RW <variable1> <prompt> RN -> RN <variable1> <prompt> RC -> RC <variable1> <prompt> RR -> RR <variable1> <string2> <prompt> RL -> RL <variable1> <string2> <value3> <prompt> RF -> RF <variable1> <prompt> RI -> RI <variable1> <prompt> Section 3.2 - Showing Line Output ═════════════════════════════════ TR -> TR <token2> <token3> <token4> ... <token7> TS -> TS <token2> <token3> <token4> ... <token7> %s -> %s<number1> <variable2> %i -> %i<number1> <variable2> %d -> %d<number1>.<number2> <value3> Section 3.3 - Colorization ══════════════════════════ ANSIC -> ANSIC <color code> $<color> -> $RED, $BLUE, $GREEN, $YELLOW, $MAGENTA, $CYAN, $WHITE, $NORM, $BLACK Hearts -> See description in main section. Section 3.4 - Other Display Commands ════════════════════════════════════ EF -> EF <pathfile1> DRAWWAITBAR -> DRAWWAITBAR <value1> LOC -> LOC <value1> <value2> MENU -> MENU <filename1> NEWPAGE <--- SUSPENDPAGEBREAK <--- RESUMEPAGEBREAK <--- PAUSE -> PAUSE <prompt> Section 4.1 - Database Selection ════════════════════════════════ DBGROUP -> DBGROUP <group identifier> DB -> DB <database number> VSCRIPT Documentation -- 39 Section 4.2 - LOAD Related Commands ═══════════════════════════════════ LOAD -> LOAD <value1> <option> DISPLAYMSG <--- DISPLAYTEXT <--- Section 4.3 - Editing Commands ══════════════════════════════ ADDCOUNT -> ADDCOUNT <value1> CLEANUP <--- DBFLAG -> DBFLAG <value1> <switch> DEL -> DEL <value1> PACK <--- QS -> QS <value1> SAVE -> See description in main section. SEARCH -> SEARCH <value1> <number2> <string3> Section 4.4 - Viewing & Writing ═══════════════════════════════ CHOOSETOPIC <--- LISTBASES <--- NEXTBASE <--- PREVBASE <--- POST <--- READSEQMSG <--- READNEWMSG <--- SCANMSG <--- SELECTBASE <--- SETQUICKSCAN <--- Section 4.5 - E-Mail Functions ══════════════════════════════ SETEMAIL <--- FEEDBACK <--- QUICKMAIL <--- READALLEMAIL <--- READEMAILFROM <--- READEMAILTO <--- SENDEMAIL <--- Section 5.1 - Buffer Commands ═════════════════════════════ BUFFER APPEND -> BUFFER APPEND <string1> BUFFER CLEAR <--- BUFFER EDIT <--- BUFFER LIST <--- VSCRIPT Documentation -- 40 Section 6.1 - Information Commands ══════════════════════════════════ CHECKFILE -> CHECKFILE <variable1> <pathfile2> FINDFIRST -> FINDFIRST <variable1> <pathfile2> FINDNEXT -> FINDNEXT <variable1> FINDFILES <--- LISTFILES <--- NEWFILES <--- RATIO <--- REVIEWFILE <--- REVIEWUPLOADS <--- SETNEWFILESSCAN -> SETNEWFILESSCAN <value1> SEARCHALL <--- TOPDOWNLOADS <--- XFERTIME -> XFERTIME <variable1> <pathfile2> Section 6.2 - Transfer Commands ═══════════════════════════════ BATCHDL <--- DLMASTERLIST <--- DOWNLOAD -> DOWNLOAD <pathfile1> DOWNLOADFILE <--- REMOTEUPLOAD <--- SYSOPUPLOAD <--- UPLOAD -> UPLOAD <pathfile1> Section 6.3 - File Editing ══════════════════════════ EDITFILE <--- CLOSE <--- KILL -> KILL <pathfile1> OPEN -> OPEN <pathfile1> <option> <option> = INPUT, OUTPUT, APPEND READ -> READ <variable1> WRITE -> WRITE <token2> <token3> <token4> ... <token7> Section 7.1 - General Redirection ═════════════════════════════════ # -> # <label> CALL -> CALL <label> GO -> GO <label> RET <--- VSCRIPT Documentation -- 41 Section 7.2 - Loops and Comparisons ═══════════════════════════════════ Section 7.21 - DO Loops ─────────────────────── -> DO <variable1> = <value2> <value3> [body of the loop] LOOP -> DO WHILE <variable1> {must store a numeric!} [body of the loop] LOOP Section 7.22 - IF/IFVAL Structures ────────────────────────────────── -> IF <variable1> <relation> <variable2> THEN [then-code] ENDIF -> IF <variable1> <relation> <variable2> THEN [then-code] ELSE [else-code] ENDIF Section 7.23 - TEST/TESTVAL Commands ════════════════════════════════════ -> TEST <variable1> <relation> <variable2> <label> -> TESTVAL <variable1> <relation> <variable2> <label> Section 7.3 - Passing Control ═════════════════════════════ LINK -> LINK <filename> EXIT -> EXIT <filename> SHELL -> SHELL <pathfile or DOS command line> DOOR -> DOOR <pathfile or DOS command line> RETURNFB -> RETURNFB <function block name> RETURNSCRIPT -> RETURNSCRIPT <script name> VSCRIPT Documentation -- 42 Section 8.1 - Visual/Interactive ════════════════════════════════ AUTOPOST <--- LISTCALLERS -> LISTCALLERS <value1> LOGOFF <--- LOGOFFYN <--- PAGESYSOP <--- RANDOM <--- STACK -> STACK <variable1> SYSINFO <--- VALIDATE <--- WHO <--- Section 8.2 - User Modifiers ════════════════════════════ ACCOUNT <--- ACTION -> ACTION <string1> ADDCREDITS -> ADDCREDITS <value1> ADDTIME -> ADDTIME <value1> SETACCFLAG -> SETACCFLAG <value1> <option> <option> = ON, OFF SETEXTRA -> SETEXTRA <value1> <string2> SETFLAGS -> SETFLAGS <variable1> <option> <option> = ON, OFF SETSL -> SETSL <value1> SETTIMELIMIT -> SETTIMELIMIT <value1> USEREDIT <--- Section 8.3 - Real Miscellany ═════════════════════════════ ! -> ! <put your comments here> & -> & <filename> BEEP <--- DELAY -> DELAY <value1> LOG -> LOG <token2> <token3> <token4> ... <token7> Appendix A - VGIX Commands ══════════════════════════ CLS <--- COLOR -> COLOR <color> LINE -> LINE <x> <y> <x2> <y2> <color> <boxflag> PLOT -> PLOT <x> <y> <color> CIRCLE -> CIRCLE <x> <y> <radius> <color> PAINT -> PAINT <x> <y> <color> <bordercolor> DRAW -> DRAW <actionstring> PLAY -> PLAY <musicstring> ICONIFY <--- ICON -> ICON <iconname> <x> <y> <orflag> <key> <capt.> VSCRIPT Documentation -- 43 ╔════════════════════════════════════════════════════════════════╗ ║ APPENDIX C -- SCRIPT/FUNCTION BLOCK COMMANDS ║ ╚════════════════════════════════════════════════════════════════╝ What follows is a list of all of the script commands that can be used in a function block (.FB) file. Any special rules that apply to the command when used in a .FB file will be listed after the command. The commands are broken down by the sections in the main part of this documentation that they are listed in. ═════════════════════════════════════════════════════════════════ Section 4.3 - Editing Commands ══════════════════════════════ CLEANUP <--- Section 4.4 - Viewing & Writing ═══════════════════════════════ CHOOSETOPIC <--- LISTBASES <--- NEXTBASE <--- PREVBASE <--- POST <--- READSEQMSG <--- READNEWMSG <--- SCANMSG <--- SELECTBASE <--- SETQUICKSCAN <--- Section 4.5 - E-Mail Functions ══════════════════════════════ FEEDBACK <--- QUICKMAIL <--- READALLEMAIL <--- READEMAILFROM <--- READEMAILTO <--- SENDEMAIL <--- Section 6.1 - Information Commands ══════════════════════════════════ FINDFILES <--- LISTFILES <--- NEWFILES <--- RATIO <--- REVIEWFILE <--- REVIEWUPLOADS <--- SETNEWFILESSCAN <--- This command can only be used to prompt the user for number of days to scan. SEARCHALL <--- TOPDOWNLOADS <--- VSCRIPT Documentation -- 44 Section 6.2 - Transfer Commands ═══════════════════════════════ BATCHDL <--- DLMASTERLIST <--- DOWNLOADFILE <--- REMOTEUPLOAD <--- SYSOPUPLOAD <--- Section 6.3 - File Editing ══════════════════════════ EDITFILE <--- Section 8.1 - Visual/Interactive ════════════════════════════════ AUTOPOST <--- LISTCALLERS <--- This command can only be used to list all the callers for the current day. LOGOFF <--- LOGOFFYN <--- PAGESYSOP <--- RANDOM <--- SYSINFO <--- VALIDATE <--- WHO <--- Section 8.2 - User Modifiers ════════════════════════════ ACCOUNT <--- USEREDIT <--- Section 8.3 - Real Miscellany ═════════════════════════════ BEEP <--- ═════════════════════════════════════════════════════════════════ What follows is a keyboard layout showing all of the available symbols that may be used within a function block (.FB). All other symbols are unusable and may cause the BBS to lock (&), do nothing (%), or give a menu (?). Also note that you can not use lowercase letters in your function block as they are ignored by VBBS, which assumes uppercase for all alphabetic characters entered by the user. It is also possible to use extended ASCII characters in a function block, although they have not all been tested. ~` ! @ # $ ^ * ( ) -_ += \| Q W E R T Y U I O P [{ ]} A S D F G H J K L ;: '" Z X C V B N M ,< .> / VSCRIPT Documentation -- 45 ╔════════════════════════════════════════════════════════════════╗ ║ APPENDIX D -- COMMON SCRIPT EXAMPLES & EXPLANATIONS ║ ╚════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════╗ ║ Note: While all the following scripts were written by other ║ ║ authors they have all undergone modification to improve ║ ║ their clarity and/or add in new features found in 6.10. ║ ║ The first few scripts are general examples, while the ║ ║ later group of scripts are specific examples of some of ║ ║ the more complex scripting command sequences. ║ ╚════════════════════════════════════════════════════════════════╝ Question: How do I figure out if it is a user's birthday? Answer: Place this section of code into the script that you wish to have show the birthday greeting. !============================================================= ! Unknown Author !============================================================= $bmonth = $birthdate LEFT 2 $month = $date LEFT 2 $bday = $birthdate MID 4 LEFT 2 $day = $date MID 4 LEFT 2 TESTVAL $bmonth <> $month NOTNOW IFVAL $bday = $day THEN <place your birthday message here> ENDIF # NOTNOW !============================================================= Question: I would like to know when I have new messages to be validated for my networked subs when I log on. Answer: Place this section of code into your START.V file anywhere before you exit. !============================================================= ! Originally written by Ken 1@8051 VirtualNET !============================================================= testval $security < 254 nothere $found = "VALIDATE.0" findfirst $validmsg "c:\vbbs\data\validate.0" test $validmsg <> $found nothere # again tr getny $choice " 5New messages to VALIDATE. 6 Validate Now? " if $choice = "Y" then validate endif # NOTHERE !============================================================= ! Note: This ONLY works for VirtualNET message bases. !============================================================= VSCRIPT Documentation -- 46 Question: How do I set up a simple downloads area for special files like virus scanners and compression utilities? Answer: Just edit the following script to show the correct paths and filenames for the files, add in the command to run the script from a function block (ex: G 001 2 SHOPPING). Then all you need to do is create a .MNU file (or a .ANS and .ASC pair) listing the user's choices and place it into your \TXT directory and away you go. !============================================================= ! Originally written by O. F. 1@2056 VirtualNET !============================================================= Example SHOP.MNU file: Available files for quick download are: A> ARJ230.EXE - Newest ARJ Compression Utility C> CLEAN102.ZIP - McAfee Virus Cleaning Utility F> FRIES.GIF - GIF of the lovable '-fries' G> GREMLIN.GIF - GIF of 'The (verbose tagline) Gremlin' P> PKZIP204G.EXE - Newest PKZip Compression Utility S> SCAN102.ZIP - McAfee Virus Scanning Utility !============================================================= tr $crlf menu shop tr $crlf rr $selection acfgpsq "Which file would you like ? <Q to quit>" IF $selection = a THEN DOWNLOAD d:\dloads\compress\arj230.exe ELSE IF $selection = c THEN DOWNLOAD d:\dloads\virus\clean102.zip ELSE IF $selection = f THEN DOWNLOAD d:\dloads\gifs\fries.gif ELSE IF $selection = g THEN DOWNLOAD d:\dloads\gifs\gremlin.gif ELSE IF $selection = p THEN DOWNLOAD d:\dloads\compress\pkz204g.exe ELSE IF $selection = s THEN DOWNLOAD d:\dloads\virus\scan102.zip ENDIF tr $crlf exit start ! Make sure the EXIT command above is to a .FB you have !! !============================================================= VSCRIPT Documentation -- 47 Question: How can I enhance the chat call from my users? I like to know WHY they chatted me, even if I am not around. Answer: All you have to do is compile the following script as CHAT.V and then and change the line in your START.FB from 'l 001 1 ^pagesysop' to 'l 001 2 chat'. !============================================================= ! Originally written by B. B. Woof 1@5096 VirtualNET !============================================================= tr "Why do you wish to page " $sysop tr tr " >----------------------------------------------------<" rs $reason "=> " tr " >----------------------------------------------------<" test $reason = "" end $tst = $reason LEFT 5 test $tst = " " end test $available = Y imhere tr tr $sysop " is not currently available, " go feed # imhere tr tr "Paging " $sysop do $count = 1 10 ts " 2< 6< 2< 6* 2> 6> 2> " $bell loop tr tr " Please wait 10 seconds for " $sysop " to respond, " tr drawwaitbar 10 do $a = 1 10 ts "*" delay 1 loop tr tr $sysop " doesn't seem to be answering..." # feed getyn $yn "Would you like to leave feedback? (Y/N/enter=yes)" tr if $yn = Y then $s = " and left feedback as well!" feedback else $s = " and did not leave feedback!" endif log $handle ", paged you at " $time " on " $date log "Chat reason: " $reason log $s tr # end exit start ! Make sure the EXIT command above is to a .FB you have !! !============================================================= VSCRIPT Documentation -- 48 !============================================================== ! Buffer Example (see Section 5 for command descriptions) !============================================================== ! EMAIL.V This sends an E-mail to the Sysop. To do this we ! create a form letter in the buffer and then write ! the buffer contents to an E-mail addressed to the ! Sysop #1 account. Note the '!' are comment lines. ! ! Create the form letter $Line1 = $Sysop & "," $Line2 = " I'm a new user and would really appreciate it" $Line3 = "if you would validate my account." $Line4 = " Thanks!" $Line5 = " " & $Handle ! Clear out any existing buffer contents Buffer Clear ! Write the text lines to the Buffer Buffer Append $Line1 Buffer Append $Line2 Buffer Append $Line3 Buffer Append $Line4 Buffer Append $Line5 ! Position to the E-mail database SetEmail ! Save the buffer as E-mail to the sysop #1 Save 1 $Node "Validation Request" 0 "" 1 ! Clear out the buffer again Buffer Clear !============================================================== VSCRIPT Documentation -- 49 !============================================================== ! File Editing Example (see Section 6 for command desc.) !============================================================== ! READ.V - Some examples of writing and reading from the ! buffer file. ! $Where = $port ! this selects the buffer $File = "c:\vbbs\b" & $where & ".tmp" ! for the node you're on ! ! Check to see if the file is there; if so, delete it. CHECKFILE $Len $File IFVAL $Len > 0 Then KILL $File ENDIF ! Build an new one, add one line, then close it. OPEN $File OUTPUT WRITE "Your Handle : " $handle CLOSE ! Now open it, add data to the end of it, then close it again. OPEN $File APPEND WRITE "The BBSName : " $bbsname WRITE "Your Baud Rate : " $baud WRITE "The Sysop's Name : " $sysop " and the time : " $time CLOSE ! Now re-open it, read the data back, print it, and close it. OPEN $File INPUT # Tag READ $Line TEST $Line = "!EOF!" End TR $Line GO Tag # End ! Now close and remove the file CLOSE KILL $File !============================================================== With very little work you could actually write an editor using the combination of the BUFFER commands and the commands above. The options are limitless once you set your mind to it. VSCRIPT Documentation -- 50 !============================================================= ! Control Example (see Section 7 for command descriptions) !============================================================= ! Waiting.V - This is a small script to force the user to ! do nothing for 30 seconds. It is also an ! example of how to use the various control ! structures to accomplish the same goals. $x = 1 $y = 0 CALL drawit !---------------------------- DO $a = 1 10 ! These CALL slowit ! three LOOP ! lines CALL drawit !---------------------------- # again ! And IFVAL $x < 11 THEN ! \ CALL slowit ! all $x = $x + 1 ! \ GO again ! nine ELSE ! \ GO notagain ! of ENDIF ! \ # notagain ! these CALL drawit !---------------------------- # lastone ! And CALL slowit ! \ $y = $y + 1 ! these TESTVAL $y = 10 alldone ! \ go lastone ! five # alldone !---------------------------- exit start ! do the same thing # drawit !---------------------------- TR DRAWWAITBAR 10 RET # slowit DELAY 1 TS "*" RET !=============================================================